/*
 * Copyright (c) 2022 Queclink-C-Library
 *
 * This file is subject to the terms and conditions of the MIT License.
 * For details, please see the LICENSE file or visit the MIT website: https://mit-license.org/
 */

#ifndef QLIBC_TIME_H
#define QLIBC_TIME_H

#include <time.h>

#include <qlibc/config.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup time
 * @ingroup common
 * @brief Declare by `#include <qlibc/time.h>`. Operations related to date and time.
 * @{
 */

/**
 * @brief   Convert the time of type `struct tm` to a string in "yyyy/mm/dd hh:mm:ss" format.
 * @param[in]  timeptr The time to be converted.
 * @param[out] str     The converted string. A minimum of 20 bytes of space is required.
 * @remark  For example:
 * @code
 * const struct tm time = {
 *   .tm_sec = 24,
 *   .tm_min = 58,
 *   .tm_hour = 13,
 *   .tm_mday = 19,
 *   .tm_mon = 7,
 *   .tm_year = 122,
 *   .tm_wday = 4,
 *   .tm_yday = 231,
 *   .tm_isdst = 0,
 * };
 * char mystr[20];
 * quec_tm2str(&time, mystr); //'mystr' will be changed to "2022/08/19 13:58:24".
 * @endcode
 * @authors Hubert.Lee, Jason.Huang
 * @date    2022/8/24
 */
void quec_tm2str(const struct tm *timeptr, char *str);

#if (PLATFORM_HAS_GMTIME_R == 1) || defined(DOXYGEN)

/**
 * @brief   Convert the time of type `time_t` to a string in "yyyy/mm/dd hh:mm:ss" format.
 * @details The time of type `time_t` is an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC.
 * @param[in]  timer The time to be converted.
 * @param[out] str   The converted string. A minimum of 20 bytes of space is required.
 * @remark  For example:
 * @code
 * const time_t timer = 1660891890;
 * char mystr[20];
 * quec_time2str(timer, mystr); //'mystr' will be changed to "2022/08/19 06:51:30".
 * @endcode
 * @authors Hubert.Lee, Jason.Huang
 * @date    2022/8/24
 */
void quec_time2str(const time_t timer, char *str);

#endif

/** time
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* QLIBC_TIME_H */
